   Copyright (C) 1992, 1993 Signum Support AB Copyright (C) 1993, 1994
Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

Alias modules
-------------

   Alias modules are the simplest kind of module:

`MNAME -a ALIASES...'
     This represents the simplest way of defining a module MNAME.  The
     `-a' flags the definition as a simple alias: CVS will treat any
     use of MNAME (as a command argument) as if the list of names
     ALIASES had been specified instead.  ALIASES may contain either
     other module names or paths.  When you use paths in aliases,
     `checkout' creates all intermediate directories in the working
     directory, just as if the path had been specified explicitly in
     the CVS arguments.

   For example, if the modules file contains:

     amodule -a first-dir

then the following two commands are equivalent:

     $ cvs co amodule
     $ cvs co first-dir

and they each would provide output such as:

     cvs checkout: Updating first-dir
     U first-dir/file1
     U first-dir/file2
     cvs checkout: Updating first-dir/sdir
     U first-dir/sdir/sfile

Regular modules
---------------

`MNAME [ options ] DIR [ FILES... ]'
     In the simplest case, this form of module definition reduces to
     `MNAME DIR'.  This defines all the files in directory DIR as
     module mname.  DIR is a relative path (from `$CVSROOT') to a
     directory of source in the source repository.  In this case, on
     checkout, a single directory called MNAME is created as a working
     directory; no intermediate directory levels are used by default,
     even if DIR was a path involving several directory levels.

   For example, if a module is defined by:

     regmodule first-dir

then regmodule will contain the files from first-dir:

     $ cvs co regmodule
     cvs checkout: Updating regmodule
     U regmodule/file1
     U regmodule/file2
     cvs checkout: Updating regmodule/sdir
     U regmodule/sdir/sfile
     $

   By explicitly specifying files in the module definition after DIR,
you can select particular files from directory DIR.  Here is an example:

     regfiles first-dir/sdir sfile

With this definition, getting the regfiles module will create a single
working directory `regfiles' containing the file listed, which comes
from a directory deeper in the CVS source repository:

     $ cvs co regfiles
     U regfiles/sfile
     $

Ampersand modules
-----------------

   A module definition can refer to other modules by including
`&MODULE' in its definition.
     MNAME [ options ] &MODULE...

   Then getting the module creates a subdirectory for each such module,
in the directory containing the module.  For example, if modules
contains

     ampermod &first-dir

   then a checkout will create an `ampermod' directory which contains a
directory called `first-dir', which in turns contains all the
directories and files which live there.  For example, the command

     $ cvs co ampermod

will create the following files:

     ampermod/first-dir/file1
     ampermod/first-dir/file2
     ampermod/first-dir/sdir/sfile

   There is one quirk/bug: the messages that CVS prints omit the
`ampermod', and thus do not correctly display the location to which it
is checking out the files:

     $ cvs co ampermod
     cvs checkout: Updating first-dir
     U first-dir/file1
     U first-dir/file2
     cvs checkout: Updating first-dir/sdir
     U first-dir/sdir/sfile
     $

   Do not rely on this buggy behavior; it may get fixed in a future
release of CVS.

Excluding directories
---------------------

   An alias module may exclude particular directories from other
modules by using an exclamation mark (`!') before the name of each
directory to be excluded.

   For example, if the modules file contains:

     exmodule -a !first-dir/sdir first-dir

   then checking out the module `exmodule' will check out everything in
`first-dir' except any files in the subdirectory `first-dir/sdir'.

Module options
--------------

   Either regular modules or ampersand modules can contain options,
which supply additional information concerning the module.

`-d NAME'
     Name the working directory something other than the module name.

`-e PROG'
     Specify a program PROG to run whenever files in a module are
     exported.  PROG runs with a single argument, the module name.

`-i PROG'
     Specify a program PROG to run whenever files in a module are
     committed.  PROG runs with a single argument, the full pathname of
     the affected directory in a source repository.  The `commitinfo',
     `loginfo', and `verifymsg' files provide other ways to call a
     program on commit.

`-o PROG'
     Specify a program PROG to run whenever files in a module are
     checked out.  PROG runs with a single argument, the module name.

`-s STATUS'
     Assign a status to the module.  When the module file is printed
     with `cvs checkout -s' the modules are sorted according to
     primarily module status, and secondarily according to the module
     name.  This option has no other meaning.  You can use this option
     for several things besides status: for instance, list the person
     that is responsible for this module.

`-t PROG'
     Specify a program PROG to run whenever files in a module are
     tagged with `rtag'.  PROG runs with two arguments: the module name
     and the symbolic tag specified to `rtag'.  It is not run when
     `tag' is executed.  Generally you will find that taginfo is a
     better solution (see user-defined logging.).

`-u PROG'
     Specify a program PROG to run whenever `cvs update' is executed
     from the top-level directory of the checked-out module.  PROG runs
     with a single argument, the full path to the source repository for
     this module.

The cvswrappers file
====================

   Wrappers allow you to set a hook which transforms files on their way
in and out of CVS.

   The file `cvswrappers' defines the script that will be run on a file
when its name matches a regular expresion. There are two scripts that
can be run on a file or directory. One script is executed on the
file/directory before being checked into the repository (this is denoted
with the `-t' flag) and the other when the file is checked out of the
repository (this is denoted with the `-f' flag).  The `-t'/`-f' feature
does not work with client/server CVS.

   The `cvswrappers' also has a `-m' option to specify the merge
methodology that should be used when a non-binary file is updated.
`MERGE' means the usual CVS behavior: try to merge the files.  `COPY'
means that `cvs update' will refuse to merge files, as it also does for
files specified as binary with `-kb' (but if the file is specified as
binary, there is no need to specify `-m 'COPY'').  CVS will provide the
user with the two versions of the files, and require the user using
mechanisms outside CVS, to insert any necessary changes.  *WARNING*: do
not use `COPY' with CVS 1.9 or earlier-such versions of CVS will copy
one version of your file over the other, wiping out the previous
contents.  The `-m' wrapper option only affects behavior when merging
is done on update; it does not affect how files are stored.  See
Binary files, for more on binary files.

   The basic format of the file `cvswrappers' is:

     wildcard     [option value][option value]...

     where option is one of
     -f           from cvs filter         value: path to filter
     -t           to cvs filter           value: path to filter
     -m           update methodology      value: MERGE or COPY
     -k           keyword expansion       value: expansion mode

     and value is a single-quote delimited value.

     *.nib    -f 'unwrap %s' -t 'wrap %s %s' -m 'COPY'
     *.c      -t 'indent %s %s'

The above example of a `cvswrappers' file states that all
files/directories that end with a `.nib' should be filtered with the
`wrap' program before checking the file into the repository. The file
should be filtered though the `unwrap' program when the file is checked
out of the repository. The `cvswrappers' file also states that a `COPY'
methodology should be used when updating the files in the repository
(that is, no merging should be performed).

   The last example line says that all files that end with `.c' should
be filtered with `indent' before being checked into the repository.
Unlike the previous example, no filtering of the `.c' file is done when
it is checked out of the repository.

The `-t' filter is called with two arguments, the first is the name of
the file/directory to filter and the second is the pathname to where
the resulting filtered file should be placed.

The `-f' filter is called with one argument, which is the name of the
file to filter from. The end result of this filter will be a file in
the users directory that they can work on as they normally would.

   Note that the `-t'/`-f' features do not conveniently handle one
portion of CVS's operation: determining when files are modified.  CVS
will still want a file (or directory) to exist, and it will use its
modification time to determine whether a file is modified.  If CVS
erroneously thinks a file is unmodified (for example, a directory is
unchanged but one of the files within it is changed), you can force it
to check in the file anyway by specifying the `-f' option to `cvs
commit' (see commit options.).

   For another example, the following command imports a directory,
treating files whose name ends in `.exe' as binary:

     cvs import -I ! -W "*.exe -k 'b'" first-dir vendortag reltag

The commit support files
========================

   The `-i' flag in the `modules' file can be used to run a certain
program whenever files are committed (see modules.).  The files
described in this section provide other, more flexible, ways to run
programs whenever something is committed.

   There are three kind of programs that can be run on commit.  They
are specified in files in the repository, as described below.  The
following table summarizes the file names and the purpose of the
corresponding programs.

`commitinfo'
     The program is responsible for checking that the commit is
     allowed.  If it exits with a non-zero exit status the commit will
     be aborted.

`verifymsg'
     The specified program is used to evaluate the log message, and
     possibly verify that it contains all required fields.  This is
     most useful in combination with the `rcsinfo' file, which can hold
     a log message template (see rcsinfo.).

`editinfo'
     The specified program is used to edit the log message, and
     possibly verify that it contains all required fields.  This is
     most useful in combination with the `rcsinfo' file, which can hold
     a log message template (see rcsinfo.).  (obsolete)

`loginfo'
     The specified program is called when the commit is complete.  It
     receives the log message and some additional information and can
     store the log message in a file, or mail it to appropriate
     persons, or maybe post it to a local newsgroup, or...  Your
     imagination is the limit!

The common syntax
-----------------

   The administrative files such as `commitinfo', `loginfo', `rcsinfo',
`verifymsg', etc., all have a common format.  The purpose of the files
are described later on.  The common syntax is described here.

   Each line contains the following:
   * A regular expression.  This is a basic regular expression in the
     syntax used by GNU emacs.

   * A whitespace separator--one or more spaces and/or tabs.

   * A file name or command-line template.

Blank lines are ignored.  Lines that start with the character `#' are
treated as comments.  Long lines unfortunately can *not* be broken in
two parts in any way.

   The first regular expression that matches the current directory name
in the repository is used.  The rest of the line is used as a file name
or command-line as appropriate.

Commitinfo
==========

   The `commitinfo' file defines programs to execute whenever `cvs
commit' is about to execute.  These programs are used for pre-commit
checking to verify that the modified, added and removed files are really
ready to be committed.  This could be used, for instance, to verify
that the changed files conform to to your site's standards for coding
practice.

   As mentioned earlier, each line in the `commitinfo' file consists of
a regular expression and a command-line template.  The template can
include a program name and any number of arguments you wish to supply
to it.  The full path to the current source repository is appended to
the template, followed by the file names of any files involved in the
commit (added, removed, and modified files).

   The first line with a regular expression matching the relative path
to the module will be used.  If the command returns a non-zero exit
status the commit will be aborted.

   If the repository name does not match any of the regular expressions
in this file, the `DEFAULT' line is used, if it is specified.

   All occurances of the name `ALL' appearing as a regular expression
are used in addition to the first matching regular expression or the
name `DEFAULT'.

   Note: when CVS is accessing a remote repository, `commitinfo' will
be run on the *remote* (i.e., server) side, not the client side (see
Remote repositories.).

Verifying log messages
======================

   Once you have entered a log message, you can evaluate that message
to check for specific content, such as a bug ID.  Use the `verifymsg'
file to specify a program that is used to verify the log message.  This
program could be a simple script that checks that the entered message
contains the required fields.

   The `verifymsg' file is often most useful together with the
`rcsinfo' file, which can be used to specify a log message template.

   Each line in the `verifymsg' file consists of a regular expression
and a command-line template.  The template must include a program name,
and can include any number of arguments.  The full path to the current
log message template file is appended to the template.

   One thing that should be noted is that the `ALL' keyword is not
supported.  If more than one matching line is found, the first one is
used.  This can be useful for specifying a default verification script
in a module, and then overriding it in a subdirectory.

   If the repository name does not match any of the regular expressions
in this file, the `DEFAULT' line is used, if it is specified.

   If the verification script exits with a non-zero exit status, the
commit is aborted.

   Note that the verification script cannot change the log message; it
can merely accept it or reject it.

   The following is a little silly example of a `verifymsg' file,
together with the corresponding `rcsinfo' file, the log message
template and an verification  script.  We begin with the log message
template.  We want to always record a bug-id number on the first line
of the log message.  The rest of log message is free text.  The
following template is found in the file `/usr/cvssupport/tc.template'.

     BugId:

   The script `/usr/cvssupport/bugid.verify' is used to evaluate the
log message.

     #!/bin/sh
     #
     #       bugid.verify filename
     #
     #  Verify that the log message contains a valid bugid
     #  on the first line.
     #
     if head -1 < $1 | grep '^BugId:[ ]*[0-9][0-9]*$' > /dev/null; then
         exit 0
     else
         echo "No BugId found."
         exit 1
     fi

   The `verifymsg' file contains this line:

     ^tc     /usr/cvssupport/bugid.edit

   The `rcsinfo' file contains this line:

     ^tc     /usr/cvssupport/tc.template

Editinfo
========

   *NOTE:* The `editinfo' feature has been rendered obsolete.  To set a
default editor for log messages use the `EDITOR' environment variable
(see Environment variables.) or the `-e' global option (see
Global options.).  See verifymsg, for information on the use
of the `verifymsg' feature for evaluating log messages.

   If you want to make sure that all log messages look the same way,
you can use the `editinfo' file to specify a program that is used to
edit the log message.  This program could be a custom-made editor that
always enforces a certain style of the log message, or maybe a simple
shell script that calls an editor, and checks that the entered message
contains the required fields.

   If no matching line is found in the `editinfo' file, the editor
specified in the environment variable `$CVSEDITOR' is used instead.  If
that variable is not set, then the environment variable `$EDITOR' is
used instead.  If that variable is not set a default will be used.  See
Committing your changes.

   The `editinfo' file is often most useful together with the `rcsinfo'
file, which can be used to specify a log message template.

   Each line in the `editinfo' file consists of a regular expression
and a command-line template.  The template must include a program name,
and can include any number of arguments.  The full path to the current
log message template file is appended to the template.

   One thing that should be noted is that the `ALL' keyword is not
supported.  If more than one matching line is found, the first one is
used.  This can be useful for specifying a default edit script in a
module, and then overriding it in a subdirectory.

   If the repository name does not match any of the regular expressions
in this file, the `DEFAULT' line is used, if it is specified.

   If the edit script exits with a non-zero exit status, the commit is
aborted.

   Note: when CVS is accessing a remote repository, or when the `-m' or
`-F' options to `cvs commit' are used, `editinfo' will not be consulted.
There is no good workaround for this; use `verifymsg' instead.

Editinfo example
----------------

   The following is a little silly example of a `editinfo' file,
together with the corresponding `rcsinfo' file, the log message
template and an editor script.  We begin with the log message template.
We want to always record a bug-id number on the first line of the log
message.  The rest of log message is free text.  The following template
is found in the file `/usr/cvssupport/tc.template'.

     BugId:

   The script `/usr/cvssupport/bugid.edit' is used to edit the log
message.

     #!/bin/sh
     #
     #       bugid.edit filename
     #
     #  Call $EDITOR on FILENAME, and verify that the
     #  resulting file contains a valid bugid on the first
     #  line.
     if [ "x$EDITOR" = "x" ]; then EDITOR=vi; fi
     if [ "x$CVSEDITOR" = "x" ]; then CVSEDITOR=$EDITOR; fi
     $CVSEDITOR $1
     until head -1|grep '^BugId:[ ]*[0-9][0-9]*$' < $1
     do  echo -n  "No BugId found.  Edit again? ([y]/n)"
         read ans
         case ${ans} in
             n*) exit 1;;
         esac
         $CVSEDITOR $1
     done

   The `editinfo' file contains this line:

     ^tc     /usr/cvssupport/bugid.edit

   The `rcsinfo' file contains this line:

     ^tc     /usr/cvssupport/tc.template

Loginfo
=======

   The `loginfo' file is used to control where `cvs commit' log
information is sent.  The first entry on a line is a regular expression
which is tested against the directory that the change is being made to,
relative to the `$CVSROOT'.  If a match is found, then the remainder of
the line is a filter program that should expect log information on its
standard input.

   If the repository name does not match any of the regular expressions
in this file, the `DEFAULT' line is used, if it is specified.

   All occurances of the name `ALL' appearing as a regular expression
are used in addition to the first matching regular expression or
`DEFAULT'.

   The first matching regular expression is used.

   See commit files, for a description of the syntax of the
`loginfo' file.

   The user may specify a format string as part of the filter.  The
string is composed of a `%' followed by a space, or followed by a single
format character, or followed by a set of format characters surrounded
by `{' and `}' as separators.  The format characters are:

s
     file name

V
     old version number (pre-checkin)

v
     new version number (post-checkin)

   All other characters that appear in a format string expand to an
empty field (commas separating fields are still provided).

   For example, some valid format strings are `%', `%s', `%{s}', and
`%{sVv}'.

   The output will be a string of tokens separated by spaces.  For
backwards compatibility, the first token will be the repository name.
The rest of the tokens will be comma-delimited lists of the information
requested in the format string.  For example, if `/u/src/master' is the
repository, `%{sVv}' is the format string, and three files (ChangeLog,
Makefile, foo.c) were modified, the output might be:

     /u/src/master ChangeLog,1.1,1.2 Makefile,1.3,1.4 foo.c,1.12,1.13

   As another example, `%{}' means that only the name of the repository
will be generated.

   Note: when CVS is accessing a remote repository, `loginfo' will be
run on the *remote* (i.e., server) side, not the client side (see
Remote repositories.).

Loginfo example
---------------

   The following `loginfo' file, together with the tiny shell-script
below, appends all log messages to the file
`$CVSROOT/CVSROOT/commitlog', and any commits to the administrative
files (inside the `CVSROOT' directory) are also logged in
`/usr/adm/cvsroot-log'.  Commits to the `prog1' directory are mailed to
ceder.

     ALL             /usr/local/bin/cvs-log $CVSROOT/CVSROOT/commitlog $USER
     ^CVSROOT        /usr/local/bin/cvs-log /usr/adm/cvsroot-log
     ^prog1          Mail -s %s ceder

   The shell-script `/usr/local/bin/cvs-log' looks like this:

     #!/bin/sh
     (echo "------------------------------------------------------";
      echo -n $2"  ";
      date;
      echo;
      cat) >> $1

Keeping a checked out copy
--------------------------

   It is often useful to maintain a directory tree which contains files
which correspond to the latest version in the repository.  For example,
other developers might want to refer to the latest sources without
having to check them out, or you might be maintaining a web site with
CVS and want every checkin to cause the files used by the web server to
be updated.

   The way to do this is by having loginfo invoke `cvs update'.  Doing
so in the naive way will cause a problem with locks, so the `cvs update'
must be run in the background.  Here is an example for unix (this
should all be on one line):

     ^cyclic-pages		(date; cat; (sleep 2; cd /u/www/local-docs;
      cvs -q update -d) &) >> $CVSROOT/CVSROOT/updatelog 2>&1

   This will cause checkins to repository directories starting with
`cyclic-pages' to update the checked out tree in `/u/www/local-docs'.

Rcsinfo
=======

   The `rcsinfo' file can be used to specify a form to edit when
filling out the commit log.  The `rcsinfo' file has a syntax similar to
the `verifymsg', `commitinfo' and `loginfo' files.  See syntax.
Unlike the other files the second part is *not* a command-line
template.  Instead, the part after the regular expression should be a
full pathname to a file containing the log message template.

   If the repository name does not match any of the regular expressions
in this file, the `DEFAULT' line is used, if it is specified.

   All occurances of the name `ALL' appearing as a regular expression
are used in addition to the first matching regular expression or
`DEFAULT'.

   The log message template will be used as a default log message.  If
you specify a log message with `cvs commit -m MESSAGE' or `cvs commit -f
FILE' that log message will override the template.

   See verifymsg, for an example `rcsinfo' file.

   When CVS is accessing a remote repository, the contents of `rcsinfo'
at the time a directory is first checked out will specify a template
which does not then change.  If you edit `rcsinfo' or its templates,
you may need to check out a new working directory.

Ignoring files via cvsignore
============================

   There are certain file names that frequently occur inside your
working copy, but that you don't want to put under CVS control.
Examples are all the object files that you get while you compile your
sources.  Normally, when you run `cvs update', it prints a line for
each file it encounters that it doesn't know about (see update output.).

   CVS has a list of files (or sh(1) file name patterns) that it should
ignore while running `update', `import' and `release'.  This list is
constructed in the following way.

   * The list is initialized to include certain file name patterns:
     names associated with CVS administration, or with other common
     source control systems; common names for patch files, object files,
     archive files, and editor backup files; and other names that are
     usually artifacts of assorted utilities.  Currently, the default
     list of ignored file name patterns is:

              RCS     SCCS    CVS     CVS.adm
              RCSLOG  cvslog.*
              tags    TAGS
              .make.state     .nse_depinfo
              *~      #*      .#*     ,*      _$*     *$
              *.old   *.bak   *.BAK   *.orig  *.rej   .del-*
              *.a     *.olb   *.o     *.obj   *.so    *.exe
              *.Z     *.elc   *.ln
              core

   * The per-repository list in `$CVSROOT/CVSROOT/cvsignore' is
     appended to the list, if that file exists.

   * The per-user list in `.cvsignore' in your home directory is
     appended to the list, if it exists.

   * Any entries in the environment variable `$CVSIGNORE' is appended
     to the list.

   * Any `-I' options given to CVS is appended.

   * As CVS traverses through your directories, the contents of any
     `.cvsignore' will be appended to the list.  The patterns found in
     `.cvsignore' are only valid for the directory that contains them,
     not for any sub-directories.

   In any of the 5 places listed above, a single exclamation mark (`!')
clears the ignore list.  This can be used if you want to store any file
which normally is ignored by CVS.

   Specifying `-I !' to `cvs import' will import everything, which is
generally what you want to do if you are importing files from a
pristine distribution or any other source which is known to not contain
any extraneous files.  However, looking at the rules above you will see
there is a fly in the ointment; if the distribution contains any
`.cvsignore' files, then the patterns from those files will be
processed even if `-I !' is specified.  The only workaround is to
remove the `.cvsignore' files in order to do the import.  Because this
is awkward, in the future `-I !' might be modified to override
`.cvsignore' files in each directory.

   Note that the syntax of the ignore files consists of a series of
lines, each of which contains a space separated list of filenames.
This offers no clean way to specify filenames which contain spaces, but
you can use a workaround like `foo?bar' to match a file named `foo bar'
(it also matches `fooxbar' and the like).  Also note that there is
currently no way to specify comments.

The history file
================

   The file `$CVSROOT/CVSROOT/history' is used to log information for
the `history' command (see history.).  This file must be created to
turn on logging.  This is done automatically if the `cvs init' command
is used to set up the repository (see Creating a repository.).

   The file format of the `history' file is documented only in comments
in the CVS source code, but generally programs should use the `cvs
history' command to access it anyway, in case the format changes with
future releases of CVS.

Expansions in administrative files
==================================

   Sometimes in writing an administrative file, you might want the file
to be able to know various things based on environment CVS is running
in.  There are several mechanisms to do that.

   To find the home directory of the user running CVS (from the `HOME'
environment variable), use `~' followed by `/' or the end of the line.
Likewise for the home directory of USER, use `~USER'.  These variables
are expanded on the server machine, and don't get any reasonable
expansion if pserver (see Password authenticated.) is in use;
therefore user variables (see below) may be a better choice to
customize behavior based on the user running CVS.

   One may want to know about various pieces of information internal to
CVS.  A CVS internal variable has the syntax `${VARIABLE}', where
VARIABLE starts with a letter and consists of alphanumberic characters
and `_'.  If the character following VARIABLE is a non-alphanumeric
character other than `_', the `{' and `}' can be omitted.  The CVS
internal variables are:

`CVSROOT'
     This is the value of the CVS root in use.  See Repository, for
     a description of the various ways to specify this.

`RCSBIN'
     In CVS 1.9.18 and older, this specified the directory where CVS
     was looking for RCS programs.  Because CVS no longer runs RCS
     programs, specifying this internal variable is now an error.

`CVSEDITOR'
`VISUAL'
`EDITOR'
     These all expand to the same value, which is the editor that CVS
     is using.  See Global options, for how to specify this.

`USER'
     Username of the user running CVS (on the CVS server machine).

   If you want to pass a value to the administrative files which the
user who is running CVS can specify, use a user variable.  To expand a
user variable, the administrative file contains `${=VARIABLE}'.  To set
a user variable, specify the global option `-s' to CVS, with argument
`VARIABLE=VALUE'.  It may be particularly useful to specify this option
via `.cvsrc' (see ~/.cvsrc.).

   For example, if you want the administrative file to refer to a test
directory you might create a user variable `TESTDIR'.  Then if CVS is
invoked as

     cvs -s TESTDIR=/work/local/tests

and the administrative file contains `sh ${=TESTDIR}/runtests', then
that string is expanded to `sh /work/local/tests/runtests'.

   All other strings containing `$' are reserved; there is no way to
quote a `$' character so that `$' represents itself.

The CVSROOT/config configuration file
=====================================

   The administrative file `config' contains various miscellaneous
settings which affect the behavior of CVS.  The syntax is slightly
different from the other administrative files.  Variables are not
expanded.  Lines which start with `#' are considered comments.  Other
lines consist of a keyword, `=', and a value.  Note that this syntax is
very strict.  Extraneous spaces or tabs are not permitted.

   Currently defined keywords are:

`RCSBIN=BINDIR'
     For CVS 1.9.12 through 1.9.18, this setting told CVS to look for
     RCS programs in the BINDIR directory.  Current versions of CVS do
     not run RCS programs; for compatibility this setting is accepted,
     but it does nothing.

`SystemAuth=VALUE'
     If VALUE is `yes', then pserver should check for users in the
     system's user database if not found in `CVSROOT/passwd'.  If it is
     `no', then all pserver users must exist in `CVSROOT/passwd'.  The
     default is `yes'.  For more on pserver, see Password authenticated.

`PreservePermissions=VALUE'
     Enable support for saving special device files, symbolic links,
     file permissions and ownerships in the repository.  The default
     value is `no'.  See Special Files for the full implications of
     using this keyword.

`TopLevelAdmin=VALUE'
     Modify the `checkout' command to create a `CVS' directory at the
     top level of the new working directory, in addition to `CVS'
     directories created within checked-out directories.  The default
     value is `no'.

     This option is useful if you find yourself performing many
     commands at the top level of your working directory, rather than
     in one of the checked out subdirectories.  The `CVS' directory
     created there will mean you don't have to specify `CVSROOT' for
     each command.  It also provides a place for the `CVS/Template'
     file (see Working directory storage.).

All environment variables which affect CVS
******************************************

   This is a complete list of all environment variables that affect CVS.

`$CVSIGNORE'
     A whitespace-separated list of file name patterns that CVS should
     ignore. See cvsignore.

`$CVSWRAPPERS'
     A whitespace-separated list of file name patterns that CVS should
     treat as wrappers. See Wrappers.

`$CVSREAD'
     If this is set, `checkout' and `update' will try hard to make the
     files in your working directory read-only.  When this is not set,
     the default behavior is to permit modification of your working
     files.

`$CVSUMASK'
     Controls permissions of files in the repository.  See File permissions.

`$CVSROOT'
     Should contain the full pathname to the root of the CVS source
     repository (where the RCS files are kept).  This information must
     be available to CVS for most commands to execute; if `$CVSROOT' is
     not set, or if you wish to override it for one invocation, you can
     supply it on the command line: `cvs -d cvsroot cvs_command...'
     Once you have checked out a working directory, CVS stores the
     appropriate root (in the file `CVS/Root'), so normally you only
     need to worry about this when initially checking out a working
     directory.

`$EDITOR'
`$CVSEDITOR'
     Specifies the program to use for recording log messages during
     commit.  `$CVSEDITOR' overrides `$EDITOR'.  See Committing your changes.

`$PATH'
     If `$RCSBIN' is not set, and no path is compiled into CVS, it will
     use `$PATH' to try to find all programs it uses.

`$HOME'
`$HOMEPATH'
`$HOMEDRIVE'
     Used to locate the directory where the `.cvsrc' file, and other
     such files, are searched.  On Unix, CVS just checks for HOME.  On
     Windows NT, the system will set HOMEDRIVE, for example to `d:' and
     HOMEPATH, for example to `\joe'.  On Windows 95, you'll probably
     need to set HOMEDRIVE and HOMEPATH yourself.

`$CVS_RSH'
     Specifies the external program which CVS connects with, when
     `:ext:' access method is specified.  See Connecting via rsh..

`$CVS_SERVER'
     Used in client-server mode when accessing a remote repository
     using RSH.  It specifies the name of the program to start on the
     server side when accessing a remote repository using RSH.  The
     default value is `cvs'.  See Connecting via rsh.

`$CVS_PASSFILE'
     Used in client-server mode when accessing the `cvs login server'.
     Default value is `$HOME/.cvspass'.  See Password authentication client.

`$CVS_CLIENT_PORT'
     Used in client-server mode when accessing the server via Kerberos.
     See Kerberos authenticated.

`$CVS_RCMD_PORT'
     Used in client-server mode.  If set, specifies the port number to
     be used when accessing the RCMD demon on the server side.
     (Currently not used for Unix clients).

`$CVS_CLIENT_LOG'
     Used for debugging only in client-server mode.  If set, everything
     send to the server is logged into ``$CVS_CLIENT_LOG'.in' and
     everything send from the server is logged into
     ``$CVS_CLIENT_LOG'.out'.

`$CVS_SERVER_SLEEP'
     Used only for debugging the server side in client-server mode.  If
     set, delays the start of the server child process the specified
     amount of seconds so that you can attach to it with a debugger.

`$CVS_IGNORE_REMOTE_ROOT'
     (What is the purpose of this variable?)

`$COMSPEC'
     Used under OS/2 only.  It specifies the name of the command
     interpreter and defaults to CMD.EXE.

`$TMPDIR'
`$TMP'
`$TEMP'
     Directory in which temporary files are located.  The CVS server
     uses `TMPDIR'.  See Global options, for a description of how
     to specify this.  Some parts of CVS will always use `/tmp' (via
     the `tmpnam' function provided by the system).

     On Windows NT, `TMP' is used (via the `_tempnam' function provided
     by the system).

     The `patch' program which is used by the CVS client uses `TMPDIR',
     and if it is not set, uses `/tmp' (at least with GNU patch 2.1).
     Note that if your server and client are both running CVS 1.9.10 or
     later, CVS will not invoke an external `patch' program.

Compatibility between CVS Versions
**********************************

   The repository format is compatible going back to CVS 1.3.  But see
Watches Compatibility, if you have copies of CVS 1.6 or older
and you want to use the optional developer communication features.

   The working directory format is compatible going back to CVS 1.5.
It did change between CVS 1.3 and CVS 1.5.  If you run CVS 1.5 or newer
on a working directory checked out with CVS 1.3, CVS will convert it,
but to go back to CVS 1.3 you need to check out a new working directory
with CVS 1.3.

   The remote protocol is interoperable going back to CVS 1.5, but no
further (1.5 was the first official release with the remote protocol,
but some older versions might still be floating around).  In many cases
you need to upgrade both the client and the server to take advantage of
new features and bugfixes, however.

Troubleshooting
***************

   If you are having trouble with CVS, this appendix may help.  If
there is a particular error message which you are seeing, then you can
look up the message alphabetically.  If not, you can look through the
section on other problems to see if your problem is mentioned there.